home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / borland / drfrank.zip / DRFRANK.TXT < prev    next >
Text File  |  1992-01-16  |  34KB  |  791 lines
  1. |=============================================================================|
  2. |                Dr. Frank & Tools                                            |
  3. |=============================================================================|
  4. PREVIOUS USERS:  See the "What's New" and "DFA2" sections for a quick
  5. update on what's new and improved.
  6.  
  7. ******** Table of sections ********
  8. Quick Start (For those who can't stand to read the full documentation)
  9. Introduction  (What is Dr. Frank & Tools)
  10. What can Dr. Frank show you???
  11. Preparing your programs for Post-mortem debugging
  12. Running Dr. Frank
  13. Interpreting the results
  14. Post-processing the log file
  15. Logical Addresses
  16. DRFRANK
  17. BUILDSYM
  18. TMAPSYM
  19. EXEMAP
  20. DFA2
  21. EXETDS
  22. What's new
  23. Support
  24.  
  25. |=============================================================================|
  26. |    Quick Start ( For those who can't stand to read the full documentation   |
  27. |=============================================================================|
  28.  
  29. If you can't bear to read the full documentation, here's how to use Dr. Frank.
  30. It's assumed you know what you're doing here.  If these steps aren't clear,
  31. please read the actual documentation below.
  32.  
  33. 1) Make sure you have the correct TOOLHELP.DLL installed, and in your path.
  34. 2) Run Windows, and run DRFRANK.EXE.
  35. 3) Do whatever makes the UAE occur.
  36. 4) Look at the log file (DRFRANK.LOG in the windows directory).
  37. 5) Go to the directory where the log file is, and run:
  38.     "DFA2 DRFRANK.LOG DRFRANK.BIN"
  39. 6) Look at the DFA.OUT file.
  40. 7) Resolve to read the full documentation, because there's a lot you're missing.
  41.  
  42.  
  43. |=============================================================================|
  44. |                             Introduction                                    |
  45. |=============================================================================|
  46.  
  47. Dr. Frank (DRFRANK.EXE) is a program that will help you perform a post-mortem
  48. on your Unrecoverable Application Errors (UAE's) with Microsoft Windows.
  49. It is part of a suite of tools (described below) to assist programmers,
  50. and was written with the programmer in mind, rather then the non-programmer.
  51.  
  52. When an exception occurs, Dr. Frank will intercept it, and write a file
  53. (or 2) to your disk with information helpful to finding the cause of the
  54. exception. Since Dr. Frank is oriented towards developers, it writes out a
  55. short, concise report by default.  If however, you do want more information,
  56. there are several .INI file options which allow you to configure the
  57. report to your needs.
  58.  
  59. Dr. Frank is similar to DRWATSON, and uses the same TOOLHELP.DLL, which
  60. is currently in beta testing. TOOLHELP.DLL is shipped with BC++ 3.0, and
  61. is also available on Compuserve.  It can be found either with DRWTSN.ZIP
  62. or as TLLHLP.ZIP on WINADV.  The names and locations may move around, so
  63. your best bet is to search across all libraries for TOOLHELP or WATSON. 
  64. DRWATSON and TOOLHELP.DLL are Microsoft products.
  65.  
  66. There are many features that are not discussed in the general "how-to"
  67. sections of this file.  If you're so inclined, feel free to read the
  68. program reference sections to get a better idea of what Dr. Frank & Tools
  69. can do.
  70.  
  71. |=============================================================================|
  72. |                      What can Dr. Frank show you???                         |
  73. |=============================================================================|
  74.  
  75. The most important feature of Dr. Frank is it's ability to show you
  76. the "call stack". The call stack shows you what calls your program was
  77. executing when the exception occured.  Additionally, if you post-process
  78. the log file, you can obtain the names and values of your local and global
  79. variables (if you have TD debug information available).
  80.  
  81. To the CPU, the call stack is just a series of addresses.  However, with
  82. a little help from you, Dr. Frank can give you the names of the functions
  83. and procedures associated with the addresses, instead of just a series of
  84. addresses.  With this information, you can very quickly pinpoint where the
  85. program is blowing up.
  86.  
  87. Additionally, Dr. Frank can show you the CPU registers at the time of
  88. the exception, as well as a disassembly of the instruction that caused the
  89. exception.
  90.  
  91. Dr. Frank can also display information concerning the state of Windows
  92. when the exception occurred.  This includes things like available memory,
  93. which version of Windows, events in the programs message queue, etc...
  94.  
  95. |=============================================================================|
  96. |               Preparing your programs for Post mortem debugging             |
  97. |=============================================================================|
  98.  
  99. In order to get function names for the call stack, you need to provide
  100. symbolic information to Dr. Frank.  Dr. Frank can work without any
  101. symbolic information, but you'll find that having symbolic information
  102. greatly enhances your ability to pinpoint the problem.
  103.  
  104. There are 2 forms of symbolic information that Dr. Frank & Tools understand:
  105. 1) .SYM files.  These are used by Dr. Frank at the time of the exception.
  106. 2) Turbo Debugger debug information.  This is used after after the
  107.     exception occurs.
  108.  
  109. There are advantages to both:
  110.  
  111. - .SYM files are used directly by Dr. Frank when the exception occurs.
  112. Thus, there is no need to run another utility afterwards.
  113.  
  114. - .SYM files can be used by other programs, such as Dr. Watson, the Windows
  115. Debug Kernel, WDEB386, etc...
  116.  
  117. - Turbo Debugger debug information contains line number information.  In
  118. addition to giving you function/procedure names, it can also give you the
  119. source file and line number for call stack entries.  You will also be able
  120. to see the names and values of your programs variables.
  121.  
  122. - Turbo Debugger debug information can "find" static functions that .SYM
  123. files might not contain information for.
  124.  
  125. There are utilities in Dr. Frank to create and use both kinds of debug
  126. information.
  127.  
  128. ======== Creating .SYM files ========
  129.  
  130. - For your own programs, you first need to create a .MAP file, and
  131. then create a .SYM file from that.
  132.  
  133.     If you're using a Borland IDE, you should select the linker options
  134.     that produces a .MAP file.
  135.  
  136.     If you're letting BCC invoke TLINK, use the "-M" option on the BCC
  137.     command line.
  138.  
  139.     If you're invoking TLINK yourself, use the "/m" command line option,
  140.     and make sure that you're not using "/x" (no map file).
  141.  
  142.     If you're using TPCW, use the /GD command line switch.
  143.  
  144.     If you're using another compiler, do whatever is necessary to create
  145.     a .MAP file with Public symbols.
  146.  
  147.     Next, if your .MAP file is from a Borland product, use TMAPSYM to
  148.     create the .SYM file for it. For instance: "TMAPSYM mymodule.map" will
  149.     create MYMODULE.SYM in the current directory.
  150.  
  151.     If you're using another compiler, use MAPSYM, provided with the MS
  152.     SDK to create the .SYM file.
  153.  
  154.     If your using a makefile, you can add TMAPSYM as another rule command
  155.     after the link.
  156.  
  157. - For programs that you don't have source to, i.e., USER.EXE, GDI.EXE,
  158. you can still create .SYM files
  159.  
  160.     The easiest way to do this is to use BUILDSYM.  To do this, make
  161.     sure that the programs that come with Dr. Frank are somewhere
  162.     in your path.
  163.  
  164.     Next, go to the directory that contains the file(s) that you want
  165.     to create .SYM files for, i.e., "C:\WINDOWS\SYSTEM"
  166.  
  167.     Lastly, type "BUILDSYM", followed by the file specification that
  168.     you want to build .SYM files for.  For instance:
  169.     "BUILDSYM *.EXE" will create .SYM files for all the .EXE files in
  170.     the current directory.
  171.  
  172.     You'll probably want to build .SYM files in the WINDOWS directory,
  173.     as well as the SYSTEM subdirectory below it.  If you have the
  174.     SDK, you may wish to make sure you have backups of the SDK provided
  175.     .SYM files, although the .SYM files created by BUILDSYM are usually
  176.     superior to the SDK provided .SYM files.
  177.  
  178. Note:  The .SYM file must be in the same directory as the .EXE or
  179. .DLL that it corresponds to.
  180.  
  181. ======== Creating T